home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / impOpen.z / impOpen
Text File  |  1998-10-30  |  21KB  |  397 lines
  1.  
  2.  
  3.  
  4. iiiimmmmppppOOOOppppeeeennnn((((3333))))                       IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                        iiiimmmmppppOOOOppppeeeennnn((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      impOpen, impOpenFd, impOpenBuf, impOpenExt, impOpenFdExt, impOpenBufExt,
  10.      impClose, impCloseFd - open/close SGI Image Format files
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<iiiimmmmpppp....hhhh>>>>
  14.  
  15.      IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnn((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffnnnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ............))));;;;
  16.  
  17.      IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnFFFFdddd((((iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ............))));;;;
  18.  
  19.      IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnBBBBuuuuffff((((vvvvooooiiiidddd ****bbbbuuuuffff,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,, ............))));;;;
  20.  
  21.      IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnEEEExxxxtttt((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffnnnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,,
  22.                           ooooffffffff____tttt ooooffffffffsssseeeetttt,,,, IIIIMMMMPPPPCCCCaaaacccchhhheeeeMMMMooooddddeeee ccccaaaacccchhhheeee,,,, ............))));;;;
  23.  
  24.      IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnFFFFddddEEEExxxxtttt((((iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,,
  25.                             ooooffffffff____tttt ooooffffffffsssseeeetttt,,,, IIIIMMMMPPPPCCCCaaaacccchhhheeeeMMMMooooddddeeee ccccaaaacccchhhheeee,,,, ............))));;;;
  26.  
  27.      IIIIMMMMPPPPIIIImmmmaaaaggggeeee**** iiiimmmmppppOOOOppppeeeennnnBBBBuuuuffffEEEExxxxtttt((((vvvvooooiiiidddd ****bbbbuuuuffff,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****mmmmooooddddeeee,,,,
  28.                              ooooffffffff____tttt ooooffffffffsssseeeetttt,,,, ............))));;;;
  29.  
  30.      iiiinnnntttt iiiimmmmppppCCCClllloooosssseeee((((IIIIMMMMPPPPIIIImmmmaaaaggggeeee ****iiiimmmmaaaaggggeeee))));;;;
  31.  
  32.      iiiinnnntttt iiiimmmmppppCCCClllloooosssseeeeFFFFdddd((((IIIIMMMMPPPPIIIImmmmaaaaggggeeee ****iiiimmmmaaaaggggeeee,,,, iiiinnnntttt ****ffffddddpppp))));;;;
  33.  
  34.      In write mode iiiimmmmppppOOOOppppeeeennnn, iiiimmmmppppOOOOppppeeeennnnFFFFdddd, iiiimmmmppppOOOOppppeeeennnnEEEExxxxtttt and iiiimmmmppppOOOOppppeeeennnnFFFFddddEEEExxxxtttt require
  35.      that these additional parameters be specified:
  36.  
  37.      uuuuiiiinnnntttt____tttt rrrraaaasssstttteeeerrrrTTTTyyyyppppeeee,,,, uuuuiiiinnnntttt____tttt ddddiiiimmmmeeeennnnssssiiiioooonnnn,,,, uuuuiiiinnnntttt____tttt xxxxSSSSiiiizzzzeeee,,,, uuuuiiiinnnntttt____tttt yyyySSSSiiiizzzzeeee,,,, uuuuiiiinnnntttt____tttt
  38.      nnnnuuuummmmCCCChhhhaaaannnnnnnneeeellllssss,,,, uuuuiiiinnnntttt____tttt iiiimmmmaaaaggggeeeeTTTTyyyyppppeeee,,,, cccchhhhaaaarrrr ****nnnnaaaammmmeeee
  39.  
  40.      where uuuuiiiinnnntttt____tttt stands for uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt.
  41.  
  42. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  43.      The _l_i_b_i_m_p library provides a number of different functions to open an
  44.      SGI Image Format file. The _i_m_p_O_p_e_n, _i_m_p_O_p_e_n_F_d, _i_m_p_O_p_e_n_E_x_t and
  45.      _i_m_p_O_p_e_n_F_d_E_x_t functions each open an SGI Image Format file for reading or
  46.      writing.
  47.  
  48.      _i_m_p_O_p_e_n opens the image file specified by _f_n_a_m_e. If _m_o_d_e is """"rrrr"""", the file
  49.      is opened for reading. If _m_o_d_e is """"wwww"""" the file is opened for writing and
  50.      created if it does not exist or truncated to zero length if it does
  51.      exist.
  52.  
  53.      _i_m_p_O_p_e_n_F_d opens the image file pointed to by the file descriptor _f_d. The
  54.      descriptor's permissions must permit the operations specified by _m_o_d_e.
  55.      That is, if _m_o_d_e is """"wwww"""", the descriptor must have write permission. In
  56.      addition, it must be possible to seek on the specified descriptor.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. iiiimmmmppppOOOOppppeeeennnn((((3333))))                       IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                        iiiimmmmppppOOOOppppeeeennnn((((3333))))
  71.  
  72.  
  73.  
  74.      At this time read/write mode is not supported for SGI Image files. Upon
  75.      successful execution both functions return a pointer to an SGI Image file
  76.      structure.
  77.  
  78.      If _i_m_p_O_p_e_n or _i_m_p_O_p_e_n_F_d open an image file for writing, a number of
  79.      additional parameters must be specified.
  80.  
  81.      _r_a_s_t_e_r_T_y_p_e     Specifies both the raster encoding method and the number
  82.                     of bytes per pixel per channel. SGI Image Format files can
  83.                     be written either uncompressed or with run length encoding
  84.                     compression and with one or two bytes per pixel per
  85.                     channel. Refer to _i_m_p._h for the supported raster types.
  86.  
  87.      _d_i_m_e_n_s_i_o_n      Specifies the number of dimensions in the image. A
  88.                     colormap file will have dimension one. A black and white
  89.                     image will have dimension two and an RGB image will have
  90.                     dimension three.
  91.  
  92.      _x_S_i_z_e, _y_S_i_z_e   Specifies the image size in pixels.
  93.  
  94.      _n_u_m_C_h_a_n_n_e_l_s    Specifies the number of image color channels. A black and
  95.                     white image has one channel while an RGB image has three
  96.                     channels.
  97.  
  98.      _i_m_a_g_e_T_y_p_e      Specifies how the image data is to be interpreted. Image
  99.                     data is either actual color values (normal), screen
  100.                     colormap indices (screen) or a colormap (colormap). Refer
  101.                     to _i_m_p._h for the supported image types.
  102.  
  103.      _n_a_m_e           Specifies a descriptive string for the image. Strings
  104.                     longer than IIIIMMMMPPPP____NNNNAAAAMMMMEEEE____MMMMAAAAXXXX characters will be truncated.
  105.                     Refer to _i_m_p._h for the value of IIIIMMMMPPPP____NNNNAAAAMMMMEEEE____MMMMAAAAXXXX. If this
  106.                     parameter is specified as NNNNUUUULLLLLLLL, the string "no name" will
  107.                     be written into the file. Use the empty string "" to write
  108.                     an empty name string into the image.
  109.  
  110.      The _i_m_p_O_p_e_n_E_x_t and _i_m_p_O_p_e_n_F_d_E_x_t functions also open an image file but in
  111.      addition allow an offset and image cache mode to be specified.  The
  112.      offset is the number of bytes into the file where the image is to be read
  113.      or written. The cache mode is used only during image reading and
  114.      specifies how the image data is to be accessed for subsequent reads. The
  115.      value of the cache mode is ignored when in writing mode (the mode is
  116.      implicitly IIIIMMMMPPPPNNNNooooCCCCaaaacccchhhheeee). The cache mode may be one of:
  117.  
  118.      IIIIMMMMPPPPNNNNooooCCCCaaaacccchhhheeee
  119.                Do not cache the image data. All subsequent image reads will be
  120.                done from the disk file or descriptor.
  121.  
  122.      IIIIMMMMPPPPHHHHeeeeaaaappppCCCCaaaacccchhhheeee
  123.                Cache the image data in storage allocated from the heap. All
  124.                subsequent image reads will be done from the data stored in the
  125.                heap cache.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. iiiimmmmppppOOOOppppeeeennnn((((3333))))                       IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                        iiiimmmmppppOOOOppppeeeennnn((((3333))))
  137.  
  138.  
  139.  
  140.      IIIIMMMMPPPPMMMMaaaappppCCCCaaaacccchhhheeee
  141.                Memory map the image file. All subsequent image reads will use
  142.                the memory mapping facility to reference the image data.
  143.  
  144.      The _i_m_p_O_p_e_n_B_u_f and _i_m_p_O_p_e_n_B_u_f_E_x_t functions allow reading an SGI Image
  145.      that is already in memory. Writing of the image is not currently
  146.      supported by these two functions. The buffer specified in the call to
  147.      _i_m_p_O_p_e_n_B_u_f and _i_m_p_O_p_e_n_B_u_f_E_x_t must not be deallocated until _i_m_p_C_l_o_s_e has
  148.      been called.
  149.  
  150.      _i_m_p_C_l_o_s_e closes an SGI Image Format file previously opened by _i_m_p_O_p_e_n or
  151.      _i_m_p_O_p_e_n_F_d. Among other tasks, _i_m_p_C_l_o_s_e closes the file descriptor
  152.      associates with image file if appropriate. If the image was opened using
  153.      _i_m_p_O_p_e_n_F_d or _i_m_p_O_p_e_n_F_d_E_x_t, the file descriptor specified in that function
  154.      call will be closed by _i_m_p_C_l_o_s_e.  _i_m_p_C_l_o_s_e_F_d performs the same function
  155.      as _i_m_p_C_l_o_s_e but it leaves open the file descriptor associated with the
  156.      image and returns it in the parameter _f_d_p. It then becomes the
  157.      responsibility of the caller to close the file descriptor when it is no
  158.      longer needed.  It is essential that either _i_m_p_C_l_o_s_e or _i_m_p_C_l_o_s_e_F_d be
  159.      called at the completion of writing an SGI Image file so that all
  160.      buffered data can be written and the image header can be updated. When an
  161.      image has been opened using _i_m_p_O_p_e_n_B_u_f or _i_m_p_O_p_e_n_B_u_f_E_x_t either close
  162.      function may be used.  If _i_m_p_C_l_o_s_e_F_d is used, -1 is returned as the file
  163.      descriptor.
  164.  
  165.      The _I_M_P_I_m_a_g_e structure contains public and private information about an
  166.      SGI Image file. This structure is identical both in size and field naming
  167.      to the _I_M_A_G_E structure defined in the header file _i_m_a_g_e._h included by
  168.      application that use the _l_i_b_i_m_a_g_e library.  While it has been common
  169.      practice to directly modify the public fields of the image structure,
  170.      this is not recommended. Macros are defined in _i_m_p._h for manipulating the
  171.      structure fields. It is strongly recommended that these macros be used to
  172.      set and get values from the image structure. The _I_M_P_I_m_a_g_e structure is
  173.      defined as follows.
  174.  
  175.           typedef struct _impImage {
  176.               /******* Public image header information (archived) */
  177.               ushort_t   imagic;         /* SGI Image file magic number */
  178.               ushort_t   type;           /* Raster type (e.g. verbatim, rle) */
  179.               ushort_t   dim;            /* Image dimension */
  180.               ushort_t   xsize;          /* X size (pixels) */
  181.               ushort_t   ysize;          /* Y size (pixels) */
  182.               ushort_t   zsize;          /* Number of channels (e.g. rgb = 3) */
  183.               __int32_t  min;            /* Minimum intensity in image */
  184.               __int32_t  max;            /* Maximum intensity in image */
  185.               __uint32_t wastebytes;     /* Padding */
  186.               char       name[IMP_NAME_MAX+1];   /* Image name */
  187.               __uint32_t colormap;       /* Image type (e.g. colormap, normal) */
  188.               /******* Private image header information (core use only) */
  189.               __int32_t  file;
  190.               ushort_t   flags;
  191.               short      dorev;
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. iiiimmmmppppOOOOppppeeeennnn((((3333))))                       IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                        iiiimmmmppppOOOOppppeeeennnn((((3333))))
  203.  
  204.  
  205.  
  206.               short      x;
  207.               short      y;
  208.               short      z;
  209.               short      cnt;
  210.               short      *ptr;
  211.               short      *base;
  212.               short      *tmpbuf;
  213.               __uint32_t offset;
  214.               __uint32_t rleend;
  215.               __uint32_t *rowstart;
  216.               __int32_t  *rowsize;
  217.               off_t      start;
  218.               IMPCacheMode cache;
  219.               void*      cachebuf;
  220.               __uint32_t cachesize;
  221.               off_t      cacheoffset;
  222.           } IMPImage;
  223.  
  224.  
  225.      where _u_s_h_o_r_t__t is _u_n_s_i_g_n_e_d _s_h_o_r_t, ___i_n_t_3_2__t is a 32-bit integer and
  226.      ___u_i_n_t_3_2__t is a 32-bit unsigned integer.
  227.  
  228.      _m_a_g_i_c               Magic number identifying this file as an SGI Image
  229.                          Format file.
  230.  
  231.      _t_y_p_e                Bitwise OR combined code indicating the raster
  232.                          encoding method and the number of bytes per pixel per
  233.                          channel. Currently, SGI Image files support either a
  234.                          verbatim, uncompressed, raster encoding or a run
  235.                          length, compressed, encoding. Both of these encodings
  236.                          are available at one or two bytes per pixel per
  237.                          channel. The header file _i_m_p._h defines codes for all
  238.                          supported combinations of encoding methods and pixel
  239.                          widths.
  240.  
  241.      _d_i_m                 Number of dimensions to the image. A colormap file
  242.                          has dimension one (i.e. length). A black and white
  243.                          image has dimension two (i.e. height and width) and
  244.                          an RGB image has dimension three (i.e. height, width
  245.                          and depth).
  246.  
  247.      _x_s_i_z_e, _y_s_i_z_e        Image size in pixels.
  248.  
  249.      _z_s_i_z_e               Number of color channels or depth. A black and white
  250.                          image has one channel while an RGB image has three
  251.                          channels.
  252.  
  253.      _m_i_n, _m_a_x            The minimum and maximum intensity values in the
  254.                          image. These values are the minimum and maximum for
  255.                          all channels combined.
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. iiiimmmmppppOOOOppppeeeennnn((((3333))))                       IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                        iiiimmmmppppOOOOppppeeeennnn((((3333))))
  269.  
  270.  
  271.  
  272.      _n_a_m_e                A descriptive name string for the image.
  273.  
  274.      _c_o_l_o_r_m_a_p            The image type. Refer to _i_m_p._h for the supported
  275.                          image type codes.  The field is named _c_o_l_o_r_m_a_p for
  276.                          compatibility with the _I_M_A_G_E structure used by the
  277.                          _l_i_b_i_m_a_g_e library.
  278.  
  279. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  280.      All image open function return a pointer to an image structure if
  281.      execution was successful. NNNNUUUULLLLLLLL is returned and _I_M_P_e_r_r_n_o is set if an
  282.      execution error has occurred.
  283.  
  284.      _i_m_p_C_l_o_s_e and _i_m_p_C_l_o_s_e_F_d return 0 if execution was successful. -1 is
  285.      returned and _I_M_P_e_r_r_n_o is set if an execution error has occurred.
  286.  
  287. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
  288.      In addition to the system error codes defined in _e_r_r_n_o._h, the following
  289.      _l_i_b_i_m_p specific error codes may be returned.
  290.  
  291.      All image open functions will fail under the following circumstances.
  292.  
  293.      IMP_ERR_READWRITE        Read/write mode is not supported.
  294.  
  295.      IMP_ERR_MEMALLOC         Dynamic memory allocation failed. This indicates
  296.                               an out-of-memory condition.
  297.  
  298.      IMP_ERR_BADMAGIC         Bad magic number in image file header. The file
  299.                               may not be and SGI Image Format file.
  300.  
  301.      IMP_ERR_BADRASTER        Unrecognized raster encoding method. Refer to
  302.                               _i_m_p._h for supported raster encodings.
  303.  
  304.      IMP_ERR_BADIMAGE         Unrecognized image type. Refer to _i_m_p._h for
  305.                               supported image types.
  306.  
  307.      In addition, _i_m_p_O_p_e_n_F_d and _i_m_p_O_p_e_n_F_d_E_x_t will fail under the following
  308.      circumstances.
  309.  
  310.      IMP_ERR_BADFD            The specified file descriptor is invalid.
  311.  
  312.      IMP_ERR_SEEK             A seek cannot be performed on the specified file
  313.                               descriptor.
  314.  
  315.      _i_m_p_O_p_e_n_B_u_f and _i_m_p_O_p_e_n_B_u_f_E_x_t may also return the following error code.
  316.  
  317.      IMP_ERR_NOWRITE          Writing mode not allowed by the function.
  318.  
  319.      _i_m_p_C_l_o_s_e and _i_m_p_C_l_o_s_e_F_d will fail under the following circumstances.
  320.  
  321.      IMP_ERR_WRITEFLAG        Attempt to write to an image file not opened for
  322.                               writing.
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. iiiimmmmppppOOOOppppeeeennnn((((3333))))                       IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                        iiiimmmmppppOOOOppppeeeennnn((((3333))))
  335.  
  336.  
  337.  
  338.      IMP_ERR_BADBPP           Unsupported bytes per pixel value. Refer to
  339.                               _i_m_p._h for supported BPP values.
  340.  
  341.      IMP_ERR_BADIMAGE         Unrecognized image type. Refer to _i_m_p._h for
  342.                               supported image types.
  343.  
  344. NNNNOOOOTTTTEEEE
  345.      The storage for the _I_M_P_I_m_a_g_e structure is allocated by the image open
  346.      function. This storage is deallocated by the _i_m_p_C_l_o_s_e and _i_m_p_C_l_o_s_e_F_d
  347.      functions.  The caller should not explicitly reallocate or deallocate any
  348.      storage related to the image structure.
  349.  
  350. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  351.      libimp(3), impReadRow(3), impReadRowB(3), mmap(2)
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.